home *** CD-ROM | disk | FTP | other *** search
/ Graphics Plus / Graphics Plus.iso / general / hdf / vst_xtra.doc < prev   
Encoding:
Text File  |  1980-02-08  |  10.6 KB  |  369 lines
  1. Vset 2.1beta doc         Jason Ng    6/6/91    1
  2.  
  3.  
  4. Jason Ng
  5. 15/May/91 
  6.  
  7.  HDF VSET 2.1beta      
  8.  
  9. These are additional routines that are added to version 2.0. Refer to the 
  10. exsting HDF Vset manual for a description of the entire Vset interface.
  11.  
  12.  
  13. Some terminology
  14.  
  15. FIELD
  16. A field is defined by the user to describe data associated with one variable.
  17. It consists of a name, type and order.  Users of Vsets typically have datasets
  18. of several variables, and hence define several fields. For example, a field 
  19. can be defined for a pressure variable to be called "pres". Its type is FLOAT,
  20. and its order is 1.
  21.  
  22. ORDER
  23. The number of distinct components in a field. Simple variables/fields like 
  24. pressure have order 1 (one distinct component, ie itself). 
  25.  
  26. VGROUP 
  27. A Vset element where links to other elements are stored. A vgroup is used to 
  28. group related elements together. Elements can be vdatas, vgroups, and other 
  29. HDF elements like raster images, palettes, etc.
  30.  
  31. VDATA
  32. A Vset element where data is stored. One vdata can store data of one or several 
  33. different fields. Fields can be of different types (integer, float, etc).
  34. See FIELD.
  35.  
  36.  
  37. VSET 2.1 VGROUP MANIPULATION ROUTINES
  38.  
  39. Vflocate()
  40. Tests if a field exists in the vdatas belonging to a vgroup.
  41. Fortran: VFLOCC
  42.  
  43. Vinqtagref()
  44. Tests if a given tag/ref pair is in a vgroup.
  45. Fortran: VFINGTR
  46.  
  47. Velts()
  48. Returns the number of elements (links) in a vgroup.
  49. Fortran: VFELTS
  50.  
  51. Vntagrefs()
  52. Returns a count of the number of tag/ref pairs in a vgroup.
  53. Fortran: VFNTR
  54.  
  55. Vgettagrefs()
  56. Returns ALL the tag/ref pairs in a vgroup.
  57. Not to be confused with Vgettagref() [VFGTR in Fortran].
  58. Fortran: VFGTTRS
  59.  
  60. Vgettagref()
  61. Returns a tag/ref pair at a specific position in the vgroup.
  62. Not to be confused with Vgettagrefs() [VFGTRS in Fortran].
  63. Fortran: VFGTTR
  64.  
  65. Vaddtagref()
  66. Inserts a tag/ref pair into a vgroup.
  67. Can be the tag/ref of non-vset elements.
  68. Fortran: VFADTR
  69.  
  70.  
  71.  
  72. VSET 2.1 HIGH-LEVEL WRITE ROUTINES
  73.  
  74. VHstoredata() 
  75. Stores data of a simple field into a vdata.
  76. Fortran: VHFSD
  77.  
  78. VHstoredatam()
  79. Stores data of a compound field into a vdata.
  80. Fortran: VHFSDM
  81.  
  82. VHmakegroup()
  83. Creates a vgroup given  some tag/ref pairs.
  84. Fortran: VHFMKGP
  85.  
  86.  
  87. Quick creation of simple Vsets in the majority of cases can be achieved using 
  88. only the High-Level Write routines.
  89. VHstoredata    - creates a vdata of a simple variable  
  90. VHstoredatam - creates a vdata of a compound variable
  91. VHmakegroup - creates a vgroup.
  92.  
  93. VHstoredata() and VHstoredatam() are 2 routines used for storing data from 
  94. arrays into a vdata. VHmakegroup() creates a new vgroup given a series of 
  95. tag/ref pairs.
  96.  
  97. VHstoredata() is used for storing a simple variable. VHstoredatam() is used only 
  98. if a compound variable is to be stored as a single field of order > 1.
  99.  
  100.  
  101. C EXAMPLE
  102.  
  103. Vset created by the C sample program:
  104.                                          
  105.  
  106. /*
  107.     SAMPLE C PROGRAM
  108.  
  109.     HDF VSET 2.1
  110.     Jason Ng NCSA MAY 1991
  111.  
  112.     This program demonstrates the use of the high-level VSET write routines.
  113.     It shows how data can be stored in vdatas, and how vgroups can be created
  114.     from vdatas, vgroups and other HDF elements.
  115.  
  116.     This example creates a file "vtesthi.hdf" that may be viewed using the
  117.     vset utility "vshow".
  118.  
  119.     DETAILS
  120.  
  121.     This example shows how pressure data  and color data can be stored as a 
  122.     vset.  To store pressure data, a field named "PRES", is defined of 
  123.     float type. The routine VHstoredata() stores the pressure values in a vdata.
  124.  
  125.     Color data comprises 3 components (red, green, blue). These can be stored as
  126.     3 different fields in 3 vdatas. But this example shows that they can be
  127.     treated as ONE field, and stored together as a compound field called "COLOR".
  128.     The number of components of a field is called its order.  In this case, 
  129.     "COLOR" has order=3. (whereas "PRES" above has order=1).
  130.  
  131.     The routine VHstoredatam() must be used to store values of a compound field.
  132.     This is similar to VHstoredata() but has an extra argument for the order
  133.     to be specified.
  134.  
  135.     Finally a vgroup is created, and the ids of the created vdatas are stored
  136.     in the vgroup. This effectively groups the vdatas together. This example
  137.     also shows that you can insert another vgroup, as well as a non-vset element
  138.     (in this case, some element with tag=7777 and ref=1) into a vgroup.
  139. */
  140.  
  141. #include "vg.h"
  142. #define fs "vtesthi.hdf"
  143. #define NP 100
  144. #define NC 60
  145. #define ORDERC 3 /* 3 color components: rgb */
  146.  
  147. main (ac,av)   int ac; char**av; {
  148.   printf("%s: tests high-level routines\n", av[0]);
  149.   printf("Creates 2 vdatas, a vgroup, and a non-vset element\n");
  150.   printf("then link them all into another vgroup\n");
  151.   printf("Vdata 1 contains an order-1 float field PRES\n");
  152.   printf("Vdata 2 contains an order-3  integer field COLOR\n\n");
  153.   printf("The non-vset element has tag=7777, ref=1\n");
  154.   doit();
  155.   printf("all done. created file %s\n", fs);
  156. }
  157.  
  158. /* ------------------------------------------------------------------ */
  159.  
  160. doit() {
  161. DF * f;
  162. float pvals[NP];
  163. int cvals[NC][ORDERC];
  164. int i,j;
  165.  
  166. int16 pid, cid; /* refs of vdatas */
  167. int16 eid; /* empty vgroup's ref  */
  168. int16 gid; /* vgroup's ref  */
  169. int16 tags[10], refs[16];
  170. char *CLS = "EXAMPLE";
  171.  
  172. /* --- generate data here --- */
  173.   for(i=0;i<NP;i++)  pvals[i] = 100.0  + i * 0.001;
  174.   for(i=0;i<NC;i++) for(j=0;j<3;j++)  cvals[i][j] =   i + j*100;
  175.  
  176.  
  177. /* ---- open a new file --- */
  178.  
  179. if (NULL==(f=DFopen(fs,DFACC_ALL,0))) { printf("open %s err\n",fs); exit(0); }
  180.  
  181. /* ---- create 2 vdatas --- */
  182. pid = VHstoredata (f, "PRES", pvals ,NP, LOCAL_FLOATTYPE, "pressure vals",CLS);
  183. if (pid  == -1) { printf(" VHstoredata store PRES err. "); }
  184.  
  185. cid  = VHstoredatam(f, "COLOR", cvals, NC, LOCAL_INTTYPE, "rgb colors", CLS, 3);
  186. if (cid  == -1) { printf(" VHstoredata store COLOR err. "); }
  187.  
  188. eid  = VHmakegroup (f, tags, refs, 0, "This is an EMPTY vgroup", CLS);
  189. if (eid  == -1) { printf(" VHmakegroup err\n"); }
  190.  
  191. /* --- create a new vgroup to store the 2 vdatas and the empty vgroup -- */
  192. tags[0] = VSDESCTAG;  refs[0] = pid;
  193. tags[1] = VSDESCTAG;  refs[1] = cid;
  194. tags[2] = VGDESCTAG;  refs[2] = eid;
  195. tags[3] = 7777 ;      refs[3] = 1;
  196.  
  197. gid  = VHmakegroup (f, tags, refs, 4, "here is a vset with 4 links", CLS);
  198. if (eid  == -1) { printf(" VHmakegroup err\n"); }
  199.  
  200. /* --- close the file --- */
  201. DFclose (f);
  202. }
  203.  
  204. FORTRAN EXAMPLE
  205.  
  206. Vset created by the Fortran sample program.
  207.                               
  208.  
  209.  
  210. c  ==================================================================    
  211. c    FORTRAN EXAMPLE
  212. c
  213. c    HDF VSET 2.1 
  214. c    Jason Ng NCSA MAY 1991
  215. c    
  216. c    This program creates a Vset to store an array of pressure values,
  217. c    and an array of color-triplets (red-green-blue). It demonstrate
  218. c    the use of the Vset high-level write routines.
  219.  
  220. c    The pressure data is stored in one vdata (pid), and the color-triplets 
  221. c    are stored in another vdata (cid). These ids are then stored together
  222. c    in a vgroup, thereby logically grouping them as one vset.
  223. c
  224. c    Note that pressure is a simple variable. It is stored using the
  225. c    function VHFSD. But color-triplet data is a compound variable, with
  226. c    3 components (red,green,blue). The function VHFSDM is used instead
  227. c    so that the order (the number of components, ie 3) can be specified.
  228. c    
  229. c    The HDF file that is created,"eh.hdf", can be looked at with the 
  230. c    Vset utility "vshow"
  231.  
  232. c  ==================================================================    
  233.     program SAMPLE
  234.  
  235.     real         pbuf(100)
  236.     integer     cbuf(3,60)
  237.     integer     i,j, npres, ncolor
  238.     integer f
  239.     integer  pid, cid, vgid
  240.     character*10  class
  241.     integer tagnums(10), refnums(10), ntagref
  242.  
  243. c    --- routines and functions used
  244.     external DFOPEN, DFCLOSE
  245.     integer    DFOPEN
  246.     external VHFSD, VHFSDM, VHFMKGP
  247.     integer    VHFSD, VHFSDM, VHFMKGP
  248.  
  249. c    --- The parameters below are defined constants from "vg.h"
  250. c    -- float and integer types
  251.     integer         T_INT, T_FLOAT 
  252.     parameter     (T_INT=2)
  253.     parameter     (T_FLOAT=3)
  254.  
  255. c    --- HDF tag for vgroup and vdata.
  256.     integer         VDATTAG, VGPTAG
  257.     parameter     (VGPTAG=1965)
  258.     parameter     (VDATTAG=1962)
  259.  
  260. c    --- full file access
  261.     integer FULLACC
  262.     parameter (FULLACC=7)
  263.  
  264. c    ------ generate pressure data -------------------
  265.         npres = 100
  266.         do 111 i=1,npres
  267.             pbuf(i) = 0.01 * i + 500
  268. 111    continue
  269. c    ------ generate color-triplet (rgb)  data -------
  270.         ncolor = 60
  271.         do 222 i=1,ncolor
  272.             do 225 j=1,3
  273.                 cbuf(j,i) = i + j * 100
  274. 225        continue
  275. 222    continue
  276.  
  277.     class = 'example'
  278.  
  279. c    --- open the HDF file
  280.     f = DFOPEN ('eh.hdf', FULLACC, 0)
  281.  
  282. c    --- store pressure values in a new vdata
  283.     pid = VHFSD (f, 'PRES', pbuf, npres, T_FLOAT, 
  284.     1                'pressure values', class)
  285.     print *, 'Pressure vdata id is ', pid
  286.  
  287. c    --- store color-triplet values in a new vdata
  288. c          Note the argument 3 (for order=3 for a triplet)
  289.  
  290.     cid = VHFSDM (f, 'RGB', cbuf, ncolor, T_INT,
  291.     1                'a set of rgb values', class, 3)
  292.     print *, 'Color-triplet vdata id is ', cid
  293.  
  294. c     --- create a new vgroup and then group the 2 vdatas into it
  295.  
  296.     tagnums(1) = VDATTAG
  297.     tagnums(2) = VDATTAG
  298.     refnums(1) = pid
  299.     refnums(2) = cid
  300.     ntagref    = 2
  301.  
  302.     vgid = VHFMKGP (f,tagnums ,refnums, ntagref,
  303.     1                    'vgroup with 2 vdatas', 
  304.     1                    class)
  305.     print *, 'Vgroup id is ', vgid
  306.  
  307. c    --- close the HDF file
  308.     call DFCLOSE (f)
  309.     print *,'HDF VSet file eh.hdf created'
  310.  
  311.     end
  312.  
  313.  
  314.  
  315. Calling Sequences 
  316.  
  317. int VHstoredata (f, field, buf, n, datatype, vsname, vsclass)
  318. DF * f;
  319. char * field;
  320. unsigned char buf[];
  321. int32 n;
  322. char * vsname, * vsclass;
  323. int datatype;
  324.  
  325. Creates a new vdata and store data for one simple field. You give it the name 
  326. and class (strings)of that vdata, and the field name (eg "PRES" for pressure), 
  327. and tell it what datatype the data will be in. The data is passed in as the 
  328. array buf[], and you tell it how many values there are (n).
  329.  
  330. Datatype is one of LOCAL_INTTYPE, LOCAL_LONGTYPE,LOCAL_FLOATTYPE, 
  331. LOCAL_CHARTYPE.
  332.  
  333. To store acompound  field, use VHstoredatam() instead.
  334.  
  335.  
  336. int VHstoredatam (f, field, buf, n, datatype, vsname, vsclass, order)
  337. DF    *f;
  338. char  *field;
  339. float buf[];
  340. int32 n;
  341. int   datatype;
  342. int   order;
  343. char *vsname, *vsclass;
  344.  
  345. Creates a new vdata and store data for one compound field. You give it the 
  346. name and class (strings)of that vdata, and the field name (eg "PLIST3" for 
  347. pressure), and tell it what datatype the data will be in. In addition, you
  348. need to tell it the order of that field. (ie, how many components there are
  349. per data item). The data is passed in as the array buf[], and you tell it 
  350. how many values there are (n).
  351.  
  352. Datatype is one of LOCAL_INTTYPE, LOCAL_LONGTYPE,LOCAL_FLOATTYPE, 
  353. LOCAL_CHARTYPE.
  354.  
  355. This routine also works for a simple field - set the order to 1. Or you can use 
  356. VHstoredata() instead.
  357.  
  358.  
  359.  
  360. int VHmakegroup (f, tagarray, refarray , n, vgname, vgclass)
  361. int tagarray[], refarray[];
  362. int n;
  363. char  *vgname, *vgclass;
  364.  
  365. Creates a new vgroup. You give it the name, class and an array of tags and refs.
  366. You also tell it how many tag/ref pairs there are.  It will create the vgroup, 
  367. and return the ref number (id) of that new vgroup.  Vgname and vgclass are any 
  368. text string to name the vgroup.
  369.